Skip to main content

Signed Payloads

caution

As of March 4, 2022, all card programs in Production using APTO's SDKs or Mobile API are required to implement Signed Payloads. This is a mandatory update that must be completed to avoid program suspension. Before applying to Production, we encourage you to sign payloads on Sandbox as well. Please follow this guide for more information, or contact programsupport@aptopayments.com with any questions.

Introduction​

Apto provides a way to verify the origin of the requests when calling certain endpoints within the Mobile API.

The following endpoint requires a signed payload:

This allows you to perform operations against these endpoints from authorized clients only. This means that before sending back a response, you can validate that the user exists in your system and is approved for a card to be created prior to sending it back to Apto. A new user will not be created until you approve them, at which point a card can be issued. This is why the signed payload has to go through your server to be signed before being sent to Apto. Not sure how signed payloads work? Please read our Usage section to learn more about implementing a server with an endpoint in charge of signing payloads.

To make this work, Apto expects you to send signed payloads using JWT assuming the feature has been enabled in the developer portal.

You can use this resource by Auth0 to learn more about JWT and use the debugger in case you encounter issues while generating the signed token.

Generate RSA key pair​

There are several ways to generate the RSA key pair, and you may already have your own. We have outlined 2 options to generate an RSA key pair, but you may choose to do this via your preferred method. Apto recommends keys longer than 1024 characters.

Reminder - Make sure you store the private key in a secure location. The private key is going to be used to sign JWT payloads when calling the verified endpoints.

Online tool​

In this page you can generate a RSA key pair (this website is not managed by Apto).

MAC OS terminal​

You can also generate a key pair in your terminal with OpenSSL. The first step is to generate the private key and store it in a file. The following example stores the key in the private.pem file.

$ openssl genrsa -out private.pem

Then, you need to extract the public key and store it in a file or display it in the terminal window, depending on your preference. The following example saves the public key in a file called public.pem.

$ openssl rsa -in private.pem -pubout -out public.pem
info

Apto's Sandbox and Production environments require two separate key pairs. When applying for Production access, you will be asked to upload a new key that is unique to the Production environment.

Upload a key​

To upload a public key, first navigate to the Developers > API Keys page in the developer portal and within the Signed Payloads section click on Add.

Paste your public key in the space dedicated for this and click Save. Be sure to format your key with the BEGIN and END tags. Don't forget to name your key - please note that key names cannot be changed.

Once your public key is saved, you will be able to view specific information about your key, including the key name, key ID, created date and the stored public key.

You can upload a maximum of two keys at a time, and both keys can be used. To specify which key needs to be used to decrypt the payload you can send the "kid" header in the JWT token.

caution

Once activated, you won't be able to call any endpoint with signed payloads enabled without supplying a JWT token. Make sure you understand how signed payloads work before activating the feature.

You can delete the key by clicking the Delete button on the right. You are required to store at least one key at all times, and a maximum of two keys.

Usage​

We recommend implementing a server with an endpoint in charge of signing the payloads. The client should send its payload to the signing endpoint to get it signed through JWT which then can be sent to the Mobile API endpoint with signed payloads enabled. Remember to set application/jwt as the Content-Type header. If you need some additional guidance on JWTs, here are a couple of YouTube videos that might be helpful:

The diagram below represents the whole request flow. In this case, we are trying to call the create user endpoint with signed payloads enabled.

Here's a resource to help you understand how the server can be implemented:

const express = require('express');
const app = express();
app.use(express.json());

const jwt = require('jsonwebtoken');
const fs = require('fs');
const privateKey = fs.readFileSync('private.key');

const port = 3000;

app.post('/sign', (req, res) => {
    // Before signing the payload, validate the caller or the body content to make sure you want to sign it.
    // For example, you may want to make sure the caller is an authorized client.

    const payload = jwt.sign(req.body, privateKey, { algorithm: 'RS256' });

    res.status(200).send({
        token: payload,
    });
});

app.listen(port, () => {
    console.log(`Listening at http://localhost:${port}`);
});

Once we have the server running and ready to sign payloads, we can call it from a client to get payloads signed before sending them to the Mobile API's create user endpoint:

curl --location --request POST 'https://localhost:3000/sign' \
--header 'Content-Type: application/json' \
--data-raw '{
 "data_points": {
   "type": "list",
   "data": [
       {
           "type": "phone",
           "country_code": "1",
           "phone_number": "2105555555",
           "verification": {"verification_id": "entity_9749a9aea2bccb7a"}
       },
       {
           "type": "id_document",
           "value": "111223333",
           "country": "US",
           "doc_type": "SSN"
       },
       {
           "type": "email",
           "email": "tony.stark@aptopayments.com"
       },
       {
           "type": "birthdate",
           "date": "1965-10-20"
       },
       {
           "type": "name",
           "first_name": "Tony",
           "last_name": "Stark"
      },
      {
           "type": "address",
           "street_one": "Malibu Point 10880",
           "street_two": "",
           "locality": "Malibu",
           "region": "CA",
           "postal_code": "90265",
           "country": "US"
      }
   ]
 }
}'

If all went well, this will return the signed payload as a JWT token in the token field of the response (according to our server implementation above):

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

We can now send this token as the payload to the Mobile API endpoint with the signed payloads feature turned on:

curl --location --request POST 'https://api.aptopayments.com/v1/user' \
--header 'Api-Key: Bearer {MOBILE_API_KEY}' \
--header 'Content-Type: application/jwt' \
--data-raw 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

When receiving the payload, the Mobile API will use the public key created when enabling signed payloads in the developer portal to make sure the request comes from the verified origin. If the request is successfully validated, the following success response will be displayed:

{
    "type": "user",
    "user_id": "crdhldr_b04f29605a018f7d72a2",
    "user_token": "{SESSION_TOKEN}",
    "user_data": {
        "type": "list",
        "data": [
            {
                "type": "phone",
                "country_code": "1",
                "phone_number": "2015555555"
            }
        ],
        "page": 0,
        "rows": 5,
        "has_more": true,
        "total_rows": 10
    }
}

Following this approach, you only need to implement one endpoint on your server in charge of signing payloads. You will use this endpoint to obtain the signed payload prior to calling the Mobile API for the create user endpoint.

Testing in sandbox​

You can test the verified endpoint in a safe environment while your card program is in Sandbox.

Apto recommends you test this feature in Sandbox after enabling it. When testing the API calls against Sandbox, make sure to append sbx in the origin of the requests to target the correct environment:

To learn more about creating users via the Mobile API, see the creating users tutorial.

You can play and experiment in the live JWT debugger with token creation.